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Business date & Close of Business day 
concept in Fineract 


What is Fineract? 


"Fineract is a mature platform 
with open APIs that provides 
a reliable, robust, and 
affordable core banking 
solution for financial 
institutions...” 


Apache Fineract 


https://fineract.apache.org 


What is Fineract used for? ка 


“For any organization, big or small, it 
provides the client data management, loan 
and savings portfolio management, 
integrated real time accounting, and social 
and financial reporting needed to bring 
digital financial services to a modern 
connected world” 


* Image by BayuGondrong on Freepik 


Dates in Fineract 7 


Submitted оп 
Created om date 


date CoB date 


Executed on date 


Last modified on date 


Transaction date 
Tenant date 


Busts Opened on date Value date 


/ Z Closed on date 


Date definitions 0956 


Ере When the transaction was created / last modified (audit 
Created date / Last modified puroses baie ule 


When the transaction was posted. Tenant date or business 
Submitted on date / Posting date date (depends on whether the logical date concept was 
introduced or not) 


The date on which the transaction occurred or to be 


Transaction date / Value date наро ia 


Tenant time-zone date; its value is tied to the tenant 


Tenant date calendar. Represents a day of the tenant time zone 


Logical date; its value is not tied to the any time zone 
Business date calendar. Represents a day of the logical / business 
calendar 


: Timeframe that logically group together actions on a 
Business day particular business date 
COB Close of Business; concept of closing a business day 


Cob date Logical date; Represents the business date for actions 
during COB job execution 


Date categories 


System date 
Tenant date 


- For audit purposes Repayment at EIS T (UTC-5) 
- UTC 2023.10.05 2023.10.06 


Tenant date 
System date 


- For business purposes (UTC) 
- Validations 2023.10.05 
20:01:13 


- Tenant timezone 


User-provided date Repayment 
- For business purpose Transaction date: 
| 2023.10.05 
- Backdated transactions Submitted on date: 


- Tenant timezone 2023.10.06 
Created on date: 
2023.10.06. 20:01:13 


Tenant date 


Date based on the tenant time zone 
- Tenant calendar 

Tenant date tied to a time zone calendar 
- Next day started at midnight 

Pro 

- Always be in sync 

Con 

- No control over the date 


- Cannot stop the time 


Time Date 
жеу. 2023.10.10 
Х > 
x x 
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23:59 
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Problems with tenant date 


The day end based on the tenant calendar 
- Not following business needs sometimes 
Execution of jobs either 
- Before midnight 
- Might not finish before midnight 
- On/After midnight 
- they are rather a start of day actions 
Regulatory compliance 


- Reports 


2023.10.05 2023.10.06 


1 
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Interest transaction , Interest transaction 


date date 


2023.10.05 2023.10.06 


Problems with tenant date [mm 


Lack of flexibility 
- Limited disaster recovery 
- Limited support for testing complex, multi-day use cases 
No real "Close of business day" support 
- Calculate and add interest / penalty transaction as part of closing the actual day 


- No particular point where new transactions are accounted to next day, but as part of closing the 
actual day the jobs which calculates and creates interest / penalty still accounted to the day we are 
"closing" 


Close of Business day concept 2 


Having a point from where new, incoming actions belong to the next day (existed) 
- If tenant date was used, this point was midnight 
The requests which were initiated on a particular business day the outcome must belong to that particular day (new) 
- Same date to be used for all related actions 
Having “Close of Business day” relevant jobs (new) 
- This jobs are using the “business day” as the relevant date and the outcome of all actions still belong to this date 
Executing CoB on business entity before accepting incoming “next day” actions (new) 
- Data consistency 
Regulatory Compliance (new) 
- The business date is crucial for regulatory reporting and compliance. Financial institutions must adhere to 


EE related to how they calculate and record transactions, making the business date a vital component of 
compliance. 


What could be the solution? 


We need at least 2 new dates 
- Business date 
- Close of business date 
We need at least 2 contexts 
- Real-time actions 
- Incoming transactions 
- Close of (business) day actions 


- Internal (job triggered) 
transactions 


Incoming repayments 


Fineract 


Repayment 
handling 


Close of Business day jobs 


Interest 
| calculation 
|22) | 2023.10.06 


Repayment 


transaction & 
Interest transacti ay 


Business date 


Date based on logical calendar 
- Business calendar 

Business date can differ from tenant time zone date 
- Next day can be started any time 

Pro 
- Date follows the business needs 

Con 


- No auto sync 


Date 


2023.10.10 


2023.10.11 


Business date EN 


It does not support time parts 
It can be managed manually (via API call) or automatically (via scheduled job) 
All business actions during the business day shall use this date: 
- Posting / submitted on date of transactions 
- Submitted on date of actions 
- (Regular) jobs 
It will be used in every situation where the transaction date / value date is not provided by the user 
If provided then the user provided date shall be validated: 
- Disbursal date 
- Posting/Submitted date 
- Reversal date 
Will not be used for audit purposes: 
- Created on date 
- Updated on date 


Business day ЕЕЕ 


Week days 
Timeframe that logically group together actions on a 
particular business date 2023.10.05. 2023.10.06. 


- Accounts, transactions, events... 


The length of the business day can vary like 


- On week days till 16:59 


2023.10.05. 16:59 2023.10.06. 17:00 
- On weekends till 16:59 of Monday 


Weekend days 


2023.10.06. 2023.10.09. 2023.10.09. 


Support 


- Disaster recovery 


- Testing g 


- Close of Business day ^ 


2023.10.06 16:59 2023.10.07 17:00 2023.10.08 17:00 


CoB date Г 


: : Е | 
Closing a business day date Inerac 


- Based on the business calendar 


During the CoB jobs this date to be used as the 
business date 


: | | Close of Business day jobs 
Usually it is in sync with business date (configurable) 
- Business date minus 1 day 
Pro 


- During the execution of CoB jobs the actions 
and transactions are still belongs to the business 
day 


How to configure in Fineract? 


- Enable “business date” 
- Global configuration 


- Set whether the “business date” and “CoB date” 
should be kept in sync 


- Set the actual "business date” ма АР! 


- Update the "business date” when ever the business 
day ends 


- via API 


- ма Job 


Business date дата model [m 


Table 
It stores the business date and the cob date m business date ( 
“id”: SERIAL, 
It can be easily extended with additional columns (for ске . STRING 
future use cases) feats О. 
/f audit fields and 
versioning 
Type: Define the type of the business date 
Values: Constraints 
a үз ашын “Туре must be UNIQUE! 
= “Миз! be initialised before first 
| 
Value: Store Ше date value an 
| ¢Value cannot be empty or null! 
Values: “Бу default it goes with 2 entries: 
- DATE without time and time zone y , 4. die | 


‘Date format is “YYYY-MM-DD” 


Business date configuration MEE NN 


Two new global configuration entries were introduced 
Enable business date (default value: false) 

When it is enabled, the business date will be used instead of the tenant date 

When it is not enabled, the business date logics are falling back to use the tenant date. 
Enable auto CoB date adjustment (default value: true) 

When it is enabled, the CoB date will be automatically recalculated based on the business date 


Formula: COB date - business date - 1 day 


When it is not enabled, the cob date will not be automatically recalculated hence need to update manually 


Business date actions via АР! [i 


To manually adjust the business date and/or cob date 


Set a date 


POST /api/vl/businessdate 


Request 

{ 
"сурет “BUSINESS DATE", 
"ust. WE edge lg 


"dateFormat": “yyyy.MM.dd" 
) 


Response 
( 
"changes": | 
"BUSINESS ПАТЕ" 1202722, 5, 13], 
) 


Business date actions via АР! i 


To fetch business dates To fetch business a particular date 


Fetch dates Fetch a particular date 


ИЕ GET /api/vl/businessdate/BUSINESS ПАТЕ 


Response 
Response 
[ 
| ( 
"type": "BUSINESS DATE", т TRECE | " 
"date": [2022, 5, 13] кестр о ч леса Пате", 
| type": "BUSINESS DATE", 
{ "date": [2023,3,2] 


"type": "СОВ DATE", } 
"дате" (2022, 35; 12] 


Business date actions via Job ШИН ИЕН 


Alternatively we can increase the business date/cob date Бу 1 day. 
Execute “Increase Business date by 1 day” job 
POST /api/v1l/jobs/32?command-executeJob 


Pseudo code 
{ 


IF (ENABLE BUSINESS DATE == TRUE) { 
/ /NALIDATION 
IF (ACTUAL BUSINESS DATE == null) { 


THROW ERROR; 

} 

IF (ENABLE AUTOMATIC COB DATE ADJUSTMENT == TRUE) { 
NEW СОВ DATE = ACTUAL BUSINESS DATE; 


} 
NEW BUSINESS DATE = ACTUAL BUSINESS DATE + 1 DAY; 


Contextual dates EE 


"The requests which were initiated on a particular business day the outcome must 
belong to that particular day” 


- Introduced contextual dates which does not got changed during the 
processing of the request 


ThreadLocalContext 
- Fetch from database and store the business date 
- All business logic shall fetch the business date from this context 


- We had to distinguish at least two situation: 
Default context 
By default context 
COB job context 
Data during the COB job execution 


Contextual dates EE 


Pseudo class 
Class ThreadLocalContextUtil | 


Based on which context we are in, the logical date should //fields 
be either the business date or the cob date Date busithesstubes 
Date cobJobDate; 

Per request basis the business dates to be fetched from Boolean isCobContext; 
the DB 

Fetching from cache is an option, but must be careful / /methods 

with it! Date getBusinessDate() | 

| IF (isCobContext == TRUE) { 
a . . RETURN cobJobDate; 
Initializing the business context must be one of the first | ELSE { 
steps RETURN businessDate; 
) 

Asynchronous event handlers must reinitialize in the ) 
ThreadLocalContextUtil } 


Refactor functionalities to retrieve the business date 
from ThreadLocalContextUtil rather than using the 
tenant date 


Changes in Fineract _ 


Modify at all the relevant places where the tenant date was used: 
- With very limited exceptions all places where the tenant date is used we need to modify to use the 
business date 
Replace system date with tenant date or business date (exceptions may apply) 
Review value date (transaction date) and posting date (submitted on date), created on date usages 
Jobs to be reviewed and enhanced 
- Majorly focusing on COB 
Native queries to be reviewed and enhanced 
Reports to be checked and enhanced 
Every table where update is supported the AbstractAuditableWithUTCDateTimeCustom 
should be implemented 
Enhance transactions and journal entries date handling to fit for business date concept 


Use case 


Apply for a loan 
Tenant date: 2022-05-23 14:22:12 
Business date: 2022-05-22 
Submitted on date: 2022-05-23 
Outcome: FAIL 
Message: The date on which a loan is submitted cannot be in the future. 
Reason: Even the tenant date is 2022-05-23, but the business date was 
2022-05-22 which means anything further that date must be considered as a 
future date. 


baasflow.com 
upstream contributions. 


To learn more about BaaSFlow and our 
www.baasflow.com 
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